Re-land the --shadow-tight retirement and close three design-token debt rows - #1942

Summary

Four low-risk design-token items from the outstanding-issues sweep, bundled because each is a pure CSS/class change with no logic, no clinical or RAG path, and no build-tooling config. Each is its own separately revertible commit. Two follow-up commits repair a ledger request that a concurrent merge invalidated, and retire the token from the three design docs that still described it as live.

• Re-land the --shadow-tight retirement onto --e1 (row #319). PR Retire the --shadow-tight role alias onto the --e1 elevation tier #1803 retired this role alias across 49 files and squash-merged as 9d8370a on 2026-08-10; the acf78bf merge on 2026-08-11 silently reverted it along with six other PRs. Re-applied against current main: 130 call sites across 67 files, plus both declarations. The alias was a pure pass-through (--shadow-tight: var(--e1) in both themes), and the @media (forced-colors: active) block scopes :root, .dark — the same html element the alias is declared on — so it already resolved through the flattened --e1: none. Value-preserving in light, dark and forced-colors. tests/design-token-contract.test.ts now sweeps the tracked src tree for both spellings (declaration and var() consumer) rather than asserting the declaration alone, so the gate no longer depends on which half of a bad merge lands. Mutation-verified in both directions.

• Re-pin five design-system contract ratchets to their measured values (#302). The baseline is a ceiling, so paying debt down leaves silent headroom. With the retirement applied: legacyShadowAliases 220 → 119, edgeOwnershipConflicts 27 → 25, rawPaddingLiterals 67 → 63, rawGapLiterals 34 → 32, layoutTransitionExceptions 12 → 11. Regenerated with --print-debt-baseline so per-path debtByPath moves with the totals — those are what findDebtPathRegressions compares. Every metric in the diff decreases; nothing is absorbed upward. Mutation-verified: reintroducing one alias now fails at both the total and the per-path level, where the old ceiling passed it silently.

• Hold the search-band count bubble in a spacing token (#275). 1.0625rem becomes --spacing-search-band-badge, consumed as h-search-band-badge / min-w-search-band-badge. Re-measured on merged main the badge role is down from this row's five files to one, because #170's convergence landed in between. Value-preserving and proven rather than inferred: compiling globals.css through @tailwindcss/postcss emits .h-search-band-badge { height: var(--spacing-search-band-badge) } and the matching min-width rule. Two arbitrary values in the same component are deliberately left raw and re-filed as their own ledger rows — the min-[414px]:max-[429px] window (the repo defines zero --breakpoint-* tokens and eight peer sites use the same raw form, so naming one is the same drift on another axis), and the three 1.0625rem hits in mode-nav/nav-slot-ink, which size <Icon> glyphs against a 12/14/16/20/24 icon scale and are a different role, not this token.

• Close out DS Track A3 (#262 parts 2 and 3). Part 3 already shipped in PR feat(design-system): ratchet raw scale literals and gate type-step selection (#262 parts 2 and 3) #1780 per #301; confirmed against the checker, not the row. Part 2 needs no work, and that was already adjudicated in docs/design-system/GATES.md §3: the decidable half of step selection ships inside check:design-system-contract, and the remaining half — which existing step a component picks — is documented there as something "nothing mechanical can" gate, with a standing instruction not to duplicate the arbitrary-value check check:type-scale already ships. §3's live status rows carried the five numbers this PR moved and are corrected in the same commit, per #301's lesson that a row understating shipped work is a duplicate-work generator. §5 is left alone deliberately — it is a dated record, not a live status surface.

• Retarget the reland ledger record after a mid-flight reconciliation. The first push queued a cancel against inbox request 210e3db5, which was correct at the time. PR chore(issues): reconcile 75 queued ledger requests #1936 then reconciled 75 queued requests — 210e3db5 among them — moving it to docs/outstanding-issues-inbox/applied/ and allocating it canonical row #319. check-docs-links.mjs replays the inbox batch to resolve link targets, so the now-dangling cancel failed CI with cancel request 2e791c01… targets missing pending request 210e3db5…. The cancel is dropped and replaced with a done against #319, which is also the better record: the work is finished rather than withdrawn, so the ledger keeps its outcome and its guard instead of discarding them.

• Retire the token from the three remaining design docs. docs/redesign/02-design-direction.md, docs/redesign/permanent-colour-direction.md and .design-sync/conventions.md each still listed --shadow-tight → --e1 as a live alias. The source retirement above had left them stating the opposite of the code. Re-audited afterwards: every surviving mention is deliberate — the GATES.md prohibition row (naming the banned token is the point), the retirement test, unrelated CLI-flag fixtures in repo-hygiene.test.ts, the superseded HANDOVER-2026-08-07.md, and a dated historical entry at process-hardening.md:454 describing a 2026-07-02 change, which would be falsified by editing.

Verification

• npm run verify:pr-local

Re-run after merging origin/main. All stages pass except one pre-existing failure unrelated to this diff, detailed below.

- completed: check:runtime, check:installed-lock-parity, format:changed, sitemap:check,
  docs:check-index, docs:check-inventory, docs:check-scripts, docs:check-links,
  check:branch-review-ledger, check:outstanding-issues, check:ledger-write-discipline,
  lint, typecheck, test, build, eval:rag:offline, check:medication-interactions
- failed: check:medication-lexicon-report (exit 1)

check:medication-lexicon-report reports docs/medication-interaction-lexicon-review.md is stale. This is pre-existing on origin/main and not caused by this branch: the diff touches zero medication, lexicon or data/ files, and a clean worktree at pristine origin/main reproduces it at both d47aa6d and 79b01b3. It is also not wired into any CI workflow — a grep over .github/workflows/ finds nothing — so it fails every local preflight while CI stays green. Filed as its own ledger row rather than fixed here: the stale file is a clinical-facing generated document, and regenerating it inside a CSS-token PR would bundle a clinical-risk artefact with unrelated chores.

Full unit suite:

Test Files  601 passed (601)
Tests  6510 passed | 4 skipped (6514)

Token contract and tailwind-merge config gates:

Test Files  2 passed (2)
Tests  69 passed (69)

Re-verified on the current tip after both the origin/main merge and the doc commits, rather than assumed: the tracked tree holds zero --shadow-tight references in src/, and every pinned ratchet still measures exactly its baseline — so neither the merge nor the doc changes moved a metric, and the pins stay honest.

UI verification not run locally: the change is value-preserving by construction and proven so at the CSS level rather than visually. --shadow-tight resolved to var(--e1) in every scope, the badge token compiles to the same 1.0625rem, and no measurement moved. There is no rendered difference for a browser gate to detect. CI covers it regardless — Production UI (1), (2), (3), Advisory UI and Lighthouse budget all pass on this head.

Risk and rollout

• Risk: Low. CSS custom-property and class changes only; no logic, no data, no API, no auth. The widest blast radius is the shadow substitution across 67 files, which is value-preserving in light, dark and forced-colors and is now pinned by a tracked-tree contract test. The main residual risk is the one this PR is fixing — that a future merge silently reverts it again — which the new gate makes loud.
• Rollback: git revert any single commit independently while the branch is open. After the squash-merge the commits fold into one, so a post-merge rollback of one item means reverting that commit's hunks by hand. The baseline re-pin is the only commit with an ordering dependency: it must not be reverted while the retirement stands, or the ratchet regains roughly 100 units of headroom.
• Provider or production effects: None. No provider-backed gate was run; nothing touches OpenAI, Supabase, hosted CI, or deployment.
• One process note for the reviewer: a follow-up commit removes an inbox request file that an earlier push had already published. That trips the pre-push ledger-write guard, which compares against the pushed branch tip, so the push used the repo's documented SKIP_LEDGER_WRITE_GUARD=1 escape hatch with the maintainer's approval. The removal is invisible in the merged result — the file appears nowhere in git diff origin/main...HEAD — and CI's own copy of the same check, which uses the main base, passes. There was no in-place repair available: the tooling forbids cancelling a cancellation by design, and a revert commit registers as the same deletion.

Clinical Governance Preflight

classifyPullRequestFiles returns clinicalRisk: true for this diff because it touches DocumentViewer, document-viewer/** and clinical-dashboard source-rendering components. Those edits are shadow-token substitutions inside className strings only — no source, citation, retrieval or document-access behaviour changes. ragRanking is false; no ranking surface is touched, so no RAG impact: line applies.

• Source-backed claims still require linked source verification before clinical use
• No patient-identifiable document workflow was introduced or expanded without explicit governance approval
• Supabase target remains Clinical KB Database (sjrfecxgysukkwxsowpy)
• Service-role keys and private document access remain server-only
• Demo/synthetic content remains clearly separated from real clinical sources
• Source metadata, review status, and outdated/unknown-source behavior remain conservative
• Deployment classification/TGA SaMD impact was checked when clinical decision-support behavior changed

Notes

• Ledger records are queued as immutable inbox requests, not written to the canonical ledger: #319, #262, #302 and #275 closed, and four new rows filed — the two #275 carve-outs (the repo-wide breakpoint-token decision, and three off-icon-scale mode-nav glyphs), plus the two findings this preflight surfaced (the stale lexicon report that no CI job runs, and Claude Code web containers shipping Node 22 with no node_modules, which fails npm ci on engine-strict before any repo script can run). Run npm run issues:reconcile after this lands.
• Two comments corroborate the original merge loss: the globals.css note that "the resting-hairline role is gone" and the token test's "unlike the --shadow-tight assertion above" both survived acf78bf while the code they describe was reverted. Both are accurate again.
• One measurement trap for anyone re-checking #262 part 2: a raw grep for text-<step> overcounts, because it also matches the --text-*: declarations and doc comments. That is the 733-vs-705 discrepancy GATES.md line 66 already warns about, and it reproduces today — a naive sweep returns 773. Use the AST class-root pass.